feat(k8s): support promql historical data queries by dangaiden · Pull Request #82 · sysdiglabs/sysdig-mcp-server

dangaiden · 2026-04-27T09:17:14Z

Enable users the ability to query historical data (if provided a timeline) from metric tools that use Sysdig Monitor with no data restrictions.

Adds optional start/end historical query parameters to all Sysdig Monitor k8s_list_* tools, enabling LLMs to query Kubernetes metrics over a past time window instead of only the current snapshot.
When provided, the underlying PromQL is wrapped in the appropriate aggregation for each tool:
- CPU/memory/pod count → avg_over_time
- Restarted pods → increase
- Unavailable pods → min_over_time >= 1
- HTTP/network errors → sum_over_time / N (rate per second)
- Inventory tools (clusters, nodes, workloads, etc.) → max_over_time > 0
When omitted, tools behave as before (instant snapshot)

Copilot

Pull request overview

Adds first-class historical querying support to the Sysdig Monitor k8s_list_* MCP tools by introducing shared start/end RFC3339 parameters, validating/resolving the time window, and wrapping PromQL appropriately for “windowed” queries while preserving legacy instant-snapshot behavior when omitted.

Changes:

Introduce shared time-window parsing/validation utilities (TimeWindow, ParseTimeWindow, WithTimeWindowParams) and apply them across k8s_list_* Monitor tools.
Update affected tools to pass GetQueryV1Params.Time (eval at end) and set a 60s timeout for windowed queries; deprecate interval for HTTP/network error tools with precedence rules + warnings.
Expand test coverage to include windowed query construction using an injected clock; document the behavior in tool docs and top-level README.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/infra/mcp/tools/utils.go	Adds shared time-window types/helpers and request arg presence detection.
internal/infra/mcp/tools/tools_suite_test.go	Adds shared test helpers for expected windowed query params and limits.
internal/infra/mcp/tools/tool_k8s_list_workloads.go	Adds start/end support, eval time + timeout, and windowed PromQL wrapping logic.
internal/infra/mcp/tools/tool_k8s_list_workloads_test.go	Adds mock clock + windowed query expectation cases.
internal/infra/mcp/tools/tool_k8s_list_underutilized_pods_memory_quota.go	Adds start/end support; wraps usage/limit in `avg_over_time` when windowed.
internal/infra/mcp/tools/tool_k8s_list_underutilized_pods_memory_quota_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_underutilized_pods_cpu_quota.go	Adds start/end support; wraps usage/quota in `avg_over_time` when windowed.
internal/infra/mcp/tools/tool_k8s_list_underutilized_pods_cpu_quota_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_top_unavailable_pods.go	Adds start/end support and Sysdig-canonical windowed unavailable semantics (`min_over_time >= 1`).
internal/infra/mcp/tools/tool_k8s_list_top_unavailable_pods_test.go	Adds mock clock + windowed semantics tests.
internal/infra/mcp/tools/tool_k8s_list_top_restarted_pods.go	Adds start/end support; uses `increase()` when windowed.
internal/infra/mcp/tools/tool_k8s_list_top_restarted_pods_test.go	Adds mock clock + windowed increase() expectations.
internal/infra/mcp/tools/tool_k8s_list_top_network_errors_in_pods.go	Adds start/end support; deprecates interval with precedence and windowed `sum_over_time/N` behavior.
internal/infra/mcp/tools/tool_k8s_list_top_network_errors_in_pods_test.go	Adds mock clock + windowed query expectations and clarifies legacy cases.
internal/infra/mcp/tools/tool_k8s_list_top_http_errors_in_pods.go	Adds start/end support; deprecates interval with precedence and windowed `sum_over_time/N` behavior.
internal/infra/mcp/tools/tool_k8s_list_top_http_errors_in_pods_test.go	Adds mock clock + windowed query expectations (including precedence over interval).
internal/infra/mcp/tools/tool_k8s_list_top_memory_consumed_workload.go	Adds start/end support; uses `avg_over_time` for windowed.
internal/infra/mcp/tools/tool_k8s_list_top_memory_consumed_workload_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_top_memory_consumed_container.go	Adds start/end support; uses `avg_over_time` for windowed.
internal/infra/mcp/tools/tool_k8s_list_top_memory_consumed_container_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_top_cpu_consumed_workload.go	Adds start/end support; uses `avg_over_time` for windowed.
internal/infra/mcp/tools/tool_k8s_list_top_cpu_consumed_workload_test.go	Adds mock clock + windowed query expectations + invalid window tests.
internal/infra/mcp/tools/tool_k8s_list_top_cpu_consumed_container.go	Adds start/end support; uses `avg_over_time` for windowed.
internal/infra/mcp/tools/tool_k8s_list_top_cpu_consumed_container_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_pod_containers.go	Adds start/end support; uses `max_over_time(...) > 0` inventory semantics when windowed.
internal/infra/mcp/tools/tool_k8s_list_pod_containers_test.go	Adds mock clock + windowed inventory semantics test.
internal/infra/mcp/tools/tool_k8s_list_nodes.go	Adds start/end support; uses `max_over_time(...) > 0` inventory semantics when windowed.
internal/infra/mcp/tools/tool_k8s_list_nodes_test.go	Adds mock clock + windowed inventory semantics test.
internal/infra/mcp/tools/tool_k8s_list_cronjobs.go	Adds start/end support; uses `max_over_time(...) > 0` inventory semantics when windowed.
internal/infra/mcp/tools/tool_k8s_list_cronjobs_test.go	Adds mock clock + windowed inventory semantics test.
internal/infra/mcp/tools/tool_k8s_list_count_pods_per_cluster.go	Adds start/end support; uses `avg_over_time` for windowed pod counts.
internal/infra/mcp/tools/tool_k8s_list_count_pods_per_cluster_test.go	Adds mock clock + windowed query expectation.
internal/infra/mcp/tools/tool_k8s_list_clusters.go	Adds start/end support; uses `max_over_time(...) > 0` inventory semantics when windowed.
internal/infra/mcp/tools/tool_k8s_list_clusters_test.go	Adds mock clock + windowed inventory semantics tests.
internal/infra/mcp/tools/README.md	Documents start/end semantics and the per-tool PromQL wrapping table + deprecation behavior.
cmd/server/main.go	Injects a system clock into all window-aware tools at registration time.
README.md	Adds a note pointing to the tool docs for windowed aggregation semantics.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tembleking

Nit: pre-existing typo in utils.go:16 — "exampes" should be "examples". Not from this PR but you're touching the file, easy drive-by fix.

Copilot

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

internal/infra/mcp/tools/utils.go:16

Examples writes to schema["exampes"], which looks like a typo and will prevent MCP JSON schema examples from being emitted/recognized. Rename the key to "examples" so tooling can surface these examples correctly.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dangaiden · 2026-04-27T17:07:56Z

All done, not taking care of the Copilot comments as per this PR.

…ools

…erplate, and add missing ParseTimeWindow unit tests

…sArg helper

… and expand test coverage

dangaiden requested review from Copilot and tembleking April 27, 2026 09:17

dangaiden requested a review from a team as a code owner April 27, 2026 09:17

Copilot started reviewing on behalf of dangaiden April 27, 2026 09:17 View session

dangaiden requested a review from alecron April 27, 2026 09:21

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread internal/infra/mcp/tools/utils.go Outdated

tembleking changed the title ~~feat:monitor historical data~~ feat(k8s): support promql historical data queries Apr 27, 2026

tembleking reviewed Apr 27, 2026

View reviewed changes

Comment thread internal/infra/mcp/tools/utils.go

tembleking reviewed Apr 27, 2026

View reviewed changes

Comment thread internal/infra/mcp/tools/utils.go

dangaiden requested a review from Copilot April 27, 2026 15:05

Copilot started reviewing on behalf of dangaiden April 27, 2026 15:05 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread internal/infra/mcp/tools/utils.go

Comment thread internal/infra/mcp/tools/tool_k8s_list_clusters_test.go

Comment thread internal/infra/mcp/tools/tools_suite_test.go Outdated

Comment thread internal/infra/mcp/tools/utils.go Outdated

dangaiden requested a review from tembleking April 27, 2026 17:07

tembleking reviewed May 4, 2026

View reviewed changes

dangaiden removed the request for review from alecron May 7, 2026 13:03

dangaiden added 12 commits May 7, 2026 17:56

feat: add start/end parameters for historical queries on k8s_list_* t…

bcf0958

…ools

refactor(tools): inline time-window helpers into utils.go

9883a6c

end in the future → clamped to now, query proceeds normally

bd0fd20

remove 7-day cap on historical query window

1ed800f

Fix Readme mention of old MCP_MAX_INTERVAL

ae99c13

Concise wording

4433094

prevent PromQL range issues, add ApplyToParams to remove handler boil…

e87fc04

…erplate, and add missing ParseTimeWindow unit tests

chore(tools): remove interval deprecation warnings and dead requestHa…

b57989c

…sArg helper

fix: correct pre-existing typo in Examples function schema key

82516ab

add happy path test for ParseTimeWindow with valid start and end

3d2ce1c

Clean up...

abb6af4

refactor(tools): cap window at 90d, guard TimeWindow methods on zero,…

f4f7e23

… and expand test coverage

dangaiden force-pushed the feat/monitor-historical branch from 3738605 to f4f7e23 Compare May 7, 2026 16:50

dangaiden requested a review from tembleking May 7, 2026 16:51

fix(test): replace expired process tree event ID

85f6615

tembleking previously approved these changes May 11, 2026

View reviewed changes

alecron previously approved these changes May 11, 2026

View reviewed changes

Bumping as minor version

bf3ff5b

dangaiden dismissed stale reviews from alecron and tembleking via bf3ff5b May 12, 2026 06:33

dangaiden requested review from alecron and tembleking May 12, 2026 06:33

tembleking approved these changes May 12, 2026

View reviewed changes

tembleking merged commit d7aec54 into main May 12, 2026
4 of 5 checks passed

tembleking deleted the feat/monitor-historical branch May 12, 2026 06:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(k8s): support promql historical data queries#82

feat(k8s): support promql historical data queries#82
tembleking merged 14 commits into
mainfrom
feat/monitor-historical

dangaiden commented Apr 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

tembleking left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dangaiden commented Apr 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

dangaiden commented Apr 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

tembleking left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dangaiden commented Apr 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants